home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / standard / monitor.z / monitor
Encoding:
Text File  |  2002-10-03  |  6.6 KB  |  131 lines
  1. MONITOR(3X)                                            Last changed: 1-8-99
  2.  
  3.  
  4. NNAAMMEE
  5.      mmoonniittoorr, mmoonnccoonnttrrooll - Prepares execution profile
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<ccmmppllrrss//mmoonn..hh>>
  9.  
  10.      ""iinntt mmoonniittoorr((iinntt _m_o_d_e, _u_n_s_i_g_n_e_d _g_r_a_i_n,, iinntt ((**_l_o_w_p_c))(()),, iinntt ((**
  11.      _h_i_g_h_p_c))(())));;""
  12.  
  13.      ""vvooiidd mmoonnccoonnttrrooll((iinntt _m_o_d_e));;""
  14.  
  15. IIMMPPLLEEMMEENNTTAATTIIOONN
  16.      IRIX systems
  17.  
  18. DDEESSCCRRIIPPTTIIOONN
  19.      NOTE: These functions have been moved from the standard C library to
  20.      the lliibbpprrooff library.  If a program needs to access these routines it
  21.      must either use the --pp option on the compiler/linker or explicitly
  22.      link with the --llpprrooff linker option.  These functions have been changed
  23.      to work correctly with dynamic shared objects (ddssooss).
  24.  
  25.      Use of the --pp option during compilation and linking automatically
  26.      generates calls to the mmoonniittoorr and mmoonnccoonnttrrooll functions.  You must
  27.      call these functions explicitly only if you want finer control over
  28.      profiling.
  29.  
  30.      The following three varieties of profiling are available:  program-
  31.      counter (pc) sampling, invocation counting, and basic block counting.
  32.      The functions described on this page provide only pc-sampling, the
  33.      ppiixxiiee(1) command must be used to get the other types of profiling
  34.      information.
  35.  
  36.      The --pp option used during linking forces the link editor (lldd) to
  37.      include a special start-up routine mmccrrtt11..oo and the lliibbpprrooff..aa library
  38.      that contains these routines.
  39.  
  40.      mmoonniittoorr((_m_o_d_e, _g_r_a_i_n, _l_o_w_p_c, _h_i_g_h_p_c)) is used to initialize pc-sampling.
  41.      _g_r_a_i_n is the number of instruction counted in one bucket.  _l_o_w_p_c and
  42.      _h_i_g_h_p_c are currently unused.  For finer control, the user can use the
  43.      mmoonnccoonnttrrooll(()) function.
  44.  
  45.      mmoonniittoorr((PPCCSS__MMAAIINN,, _g_r_a_i_n,, 00,, 00)) specifies that only the MAIN module of
  46.      a shared program is included for program counter sampling.
  47.      mmoonniittoorr((PPCCSS__WWHHOOLLEE,, _g_r_a_i_n,, 00,, 00)) specifies that the whole program
  48.      (including dynamic shared libraries) is included for program counter
  49.      sampling.  mmoonniittoorr((PPCCSS__MMAAIINN,, _g_r_a_i_n,, 00,, 00)) and mmoonniittoorr((PPCCSS__WWHHOOLLEE,,
  50.      _g_r_a_i_n,, 00,, 00)) are equivalent for nonshared programs.
  51.  
  52.      To profile the entire program without mmccrrtt11..oo, specify the following:
  53.  
  54.           monitor (PCS_WHOLE, 2, 0, 0);
  55.  
  56.      To stop execution monitoring and write the results into an output
  57.      file, specify the following:
  58.  
  59.           moncontrol (PCS_DONE);
  60.  
  61.      mmoonnccoonnttrrooll selectively disables and re-enables pc-sampling within a
  62.      program.  To disable pc-sampling, specify the following:
  63.  
  64.           moncontrol (PCS_SUSPEND);
  65.  
  66.      To resume, specify the following:
  67.  
  68.           moncontrol (PCS_RESUME);
  69.  
  70.      This is done automatically by a special eexxiitt function linked in with
  71.      mmccrrtt11..oo.
  72.  
  73.      This allows the cost of particular operations to be measured.  If any
  74.      profiling is enabled, mmoonnccoonnttrrooll cannot prevent the program from
  75.      generating a file of profiling information on exit.
  76.  
  77.      The location of the profiling output files, and whether or not calls
  78.      to monitor will cause pc-sampling to be started, are determined by the
  79.      PPRROOFFDDIIRR environment variable.  If PPRROOFFDDIIRR is not set, the results will
  80.      be placed in a file called mmoonn..oouutt in the current directory (unless,
  81.      as explained later in this man page, shared address processes are
  82.      being pc-sampled).  If PPRROOFFDDIIRR is set to a nonempty string, it
  83.      constructs a file name of the form _p_r_o_f_d_i_r/_p_r_o_g_n_a_m_e._m_o_n._p_i_d, where
  84.      _p_r_o_f_d_i_r comes from the environment variable, _p_i_d is the process id,
  85.      and _p_r_o_g_n_a_m_e is the aarrggvv[[00]] for the process.
  86.  
  87.      It is also possible via mmoonnccoonnttrrooll to profile parts of a program,
  88.      write those results to a file, and continue profiling.  The following
  89.      function causes the current contents of the profiling buffer to be
  90.      written to a file of the form pprrooffddiirr//pprrooggnnaammee..mmoonn..ppiidd..pphhaassee__iidd or
  91.      mmoonn..oouutt..pphhaassee__iidd; _p_h_a_s_e__i_d is the string pp<<_n>>, where <_n> starts from 1
  92.      and increments for each call to mmoonnccoonnttrrooll((PPCCSS__NNEEWWPPHHAASSEE)):
  93.  
  94.           moncontrol (PCS_NEWPHASE);
  95.  
  96.      The profiling buffer is cleared after every call to mmoonnccoonnttrrooll.
  97.  
  98.      If a program that is performing pc-sampling executes the ffoorrkk(2)
  99.      system call, the profiling information is duplicated, and each will
  100.      continue to pc-sample into their own buffer.  However, it is important
  101.      that PPRROOFFDDIIRR be defined, otherwise the last process to exit will
  102.      overwrite the values in mmoonn..oouutt of the rest.
  103.  
  104.      If a program that is performing pc-sampling executes the sspprroocc(2)
  105.      system call, mmccrrtt11..oo initiates profiling for the new process.  At exit
  106.      time, regardless of whether PPRROOFFDDIIRR is set, unique file names will be
  107.      created.
  108.  
  109. FFIILLEESS
  110.      mmoonn..oouutt
  111.           Default name for output file
  112.  
  113.      lliibbpprrooff..aa
  114.           Routines for pc-sampling
  115.  
  116.      //uussrr//lliibb//mmccrrtt11..oo
  117.           Special start-up routine for pc-sampling
  118.  
  119. DDIIAAGGNNOOSSTTIICCSS
  120.      mmoonniittoorr returns 0 on failure due to insufficient memory.  It returns 1
  121.      for a successful call.  If the result file cannot be created or
  122.      written to, an error message is printed on ssttddeerrrr and a 0 is returned.
  123.      mmoonniittoorr forces the caller to exit on a failed call to mmoonniittoorr.
  124.  
  125. SSEEEE AALLSSOO
  126.      cccc(1), ppiixxiiee(1), pprrooff(1), lldd(1)
  127.  
  128.      ffoorrkk(2), pprrooffiill(2), sspprrooffiill(2), sspprroocc(2)
  129.  
  130.      This man page is available only online.
  131.